/*
Hermes Core: General Purpose Mobile Agent Platform
Copyright (C) 2006 UNICAM - Università degli Studi di Camerino

Group leaders: Flavio Corradini and Emanuela Merelli

Developers: Ezio Bartocci, Diego Bonura, Rosario Culmone,
Davide Lorenzoli, Leonardo Mariani, Francesca Piersigilli, 
Lorenzo Scortichini, Leonardo Vito.

GNU Lesser Public License

This library is free software; you can redistribute it 
and/or modify it under the terms of the GNU Lesser General 
Public License as published by the Free Software Foundation, 
version 2.1 of the License.

This library is distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty of 
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public 
License along with this library; if not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.

Emanuela Merelli
Dipartimento di Matematica ed Informatica
Università di Camerino
via Madonna delle Carceri, 62032 Camerino, Italy
E.Mail: emanuela.merelli@unicam.it
*/
package hermesV2.core.id;

import hermesV2.PlaceAddress;

import hermesV2.agent.Identificator;


/**
 * Interface that manages the BornAgent table and update the current position
 * of an <CODE>UserAgent</CODE>
 *
 * @author Diego Bonura
 *
 */
public interface Trace {
    /**
     * Returns the <CODE>PlaceAddress</CODE> of a specific
     * <CODE>UserAgent</CODE>, if the UserAgent is not born in the current
     * place returns null.
     *
     * @param id The <CODE>Identificator</CODE> of the <CODE>UserAgent</CODE>.
     *
     * @return the <CODE>PlaceAddress</CODE> where the <CODE>UserAgent</CODE>
     *         resides.
     */
    PlaceAddress getCurrentAddress(Identificator id);

    /**
     * Returns the <CODE>PlaceAddress</CODE> of a specific
     * <CODE>UserAgent</CODE>, if the UserAgent is not born in the current
     * place returns null.
     *
     * @param id The string of the <CODE>Identificator</CODE> of the
     *        <CODE>UserAgent</CODE>.
     *
     * @return the <CODE>PlaceAddress</CODE> where the <CODE>UserAgent</CODE>
     *         resides.
     */
    PlaceAddress getCurrentAddress(String id);

    /**
     * Adds the Agent (born in the current place) Identificator to the
     * platform.
     * @param placeAddress The place address where the agent is born.
     * @param id The Agent <CODE>Identificator</CODE>
     */
    void addBornAgentIdentificator(Identificator id, PlaceAddress placeAddress);

    /**
     * Updates the current position of an <CODE>UserAgent</CODE> born in the
     * current place.
     *
     * @param id The <CODE>Identificator</CODE> of the <CODE>UserAgent</CODE>
     * @param pa The current <CODE>PlaceAddress</CODE> of the
     *        <CODE>UserAgent</CODE>.
     * @return The place address where the agent is running now.
     */
    PlaceAddress updateAgentAddress(Identificator id, PlaceAddress pa);

    /**
     * This method erases the agent identificator into the agentsTable
     *
     * @param id The identificator of the agent.
     *
     * @return True if the identificator is on the table False otherwise.
     */
    boolean eraseAgentAddress(Identificator id);

    /**
     * This method returns all the identificators of the born agent table.
     *
     * @return Aa array of string of identificators.
     */
    String[] getAllBornsAgentsIdentificators();
}
